home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Source Code / Libraries / PixMaps 1.1 / Example / CSApp.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-07-10  |  11.1 KB  |  279 lines  |  [TEXT/MPS ]
  1.  
  2. #ifndef __CSAPP__
  3. #define __CSAPP__
  4.  
  5. /* file CSApp.h Copyright (C) 1996, 1997 by John R. Montbriand.  All Rights Reserved.
  6.     callback skeleton application, definitions.
  7.     Copyright (c) 1996, 1997 by John Montbriand.  All Rights Reserved.
  8.     Permission hereby granted for public use.
  9.         Distribute freely in areas where the laws of copyright apply.
  10.     USE AT YOUR OWN RISK.
  11.     DO NOT DISTRIBUTE MODIFIED COPIES.
  12.     Comments/questions/postcards* to the author at the address:
  13.       John Montbriand
  14.       P.O. Box. 1133
  15.       Saskatoon Saskatchewan Canada
  16.       S7K 3N2
  17.     or by email at:
  18.       tinyjohn@sk.sympatico.ca
  19.     *if you mail a postcard, then I will provide you with technical support
  20.     regarding questions you may have about this file.
  21. */
  22.  
  23. #include <Types.h>
  24. #include <QuickDraw.h>
  25. #include <Menus.h>
  26. #include <Windows.h>
  27. #include <Dialogs.h>
  28. #include <AppleEvents.h>
  29.  
  30. /* version of this interface */
  31. #define kCSAppVersion 1
  32.  
  33.  
  34. /* ASSORTED UTILITIES */
  35.  
  36. /* TrapAvail returns true if the indicated trap is defined. */
  37. Boolean TrapAvail(unsigned short theTrap);
  38.  
  39. /* GotReqParam checks the appleEvent to ensure all of the required
  40.     parameters are present. */
  41. OSErr GotReqParam(const AppleEvent *apple_event);
  42.  
  43.  
  44.  
  45.  
  46. /* EDITING COMMANDS */
  47.  
  48. /* standard edit menu items */
  49. #define iUndo 1
  50. #define iCut 3
  51. #define iCopy 4
  52. #define iPaste 5
  53. #define iClear 6
  54.  
  55. /* DialogEdit is automatically called by CallEditCommand and you should only
  56.     have to call it if you define your own EditDialogFunc. It calls DialogCut,
  57.     DialogCopy, DialogPaste, or DialogDelete. */
  58. void DialogEdit(short itemno);
  59.  
  60. /* CallEditCommand dispatches the editing command to the correct handler depending
  61.     on windowKind field of the current front window.  Either DialogEdit, the
  62.     EditDialogFunc, or the EditWindowFunc will be called. */
  63. void CallEditCommand(short editcmd);
  64.  
  65.  
  66.  
  67.  
  68. /* MAIN DRIVER ROUTINES */
  69.  
  70. /* OpenCSApp does all of the necessary initialization required for macintosh
  71.     applications.  stack_kilobytes should be set to the number of additional kilobytes
  72.     you want over the default stack size, and masterblocks is the number of master
  73.     pointer blocks to be allocated */
  74. OSErr OpenCSApp(long stack_kilobytes, long masterblocks);
  75.  
  76. /* CSAppEvent does all of the event handling for the event record parameter
  77.     calling any of the callbacks below.  Normally, you do not have to call CSAppEvent
  78.     as RunCSApp calls it for you, however, if you collect events yourself you
  79.     can pass the event record to CSAppEvent after you are done with it. */
  80. void CSAppEvent(EventRecord *ev);
  81.  
  82. /* RunCSApp calls GetNextEvent or WaitNextEvent (depending on what is available)
  83.     and passes the resulting event record to CSAppEvent.  the result value is
  84.     the value returned by GetNextEvent or WaitNextEvent.  NOTE:  CSAppEvent
  85.     is called for nullEvents too. */
  86. Boolean RunCSApp(long sleep);
  87.  
  88. /* CSAppGetEvent calls either GetNextEvent or WaitNextEvent depending on what
  89.     is defined passing the event record to the routine and returns the result. 
  90.     RunCSApp calls CSAppGetEvent before calling CSAppEvent.  You can
  91.     call CSAppGetEvent and CSAppEvent yourself if you want to put some additional
  92.     processing between these calls.  */
  93. Boolean CSAppGetEvent(EventRecord *ev, long sleep);
  94.  
  95. /* CloseCSApp closes the application.  Presently, it only calls ExitToShell(). This
  96.     routine never returns. */
  97. void CloseCSApp(void);
  98.  
  99.  
  100.  
  101.  
  102. /* MENU COMMANDS */
  103.     
  104. /* MenuResetFunc is called just before MenuSelect or MenuKey providing your application
  105.     a chance to enable the menus correctly for the present program state. */
  106. typedef void (*MenuResetFunc)(void);
  107.  
  108. /* MenuHandlerFunc is called after MenuSelect or MenuKey if a menu selection has
  109.     been made.  menu and item will describe the selection, modifiers is the modifiers
  110.     flags from the event record and the_menu is a handle to the menu. */
  111. typedef void (*MenuHandlerFunc)(short menu, short item, short modifiers, MenuHandle the_menu);
  112.  
  113.  
  114. /* SetMenuFunctions sets the reset and handler function for all menu commands.  if menubarID
  115.     is not zero, then the menu bar is set to the indicated menu bar resource read from
  116.     the application's resource fork. */
  117. OSErr SetMenuFunctions(short menubarID, MenuResetFunc reset, MenuHandlerFunc handler);
  118.  
  119.  
  120.  
  121.  
  122. /* DIALOG COMMANDS */
  123.  
  124. /* DialogEventFunc is called for dialog windows before IsDialogEvent or DialogSelect
  125.     is called.  This allows your application time to do any special event filtering
  126.     required for dialogs. */
  127. typedef void (*DialogEventFunc)(DialogPtr dialog, EventRecord *ev);
  128.  
  129. /* DialogHitFunc is called for dialogs whenever DialogSelect returns true.  itemhit
  130.     is the item number returned by DialogSelect, and modifiers is the modifiers
  131.     field copied from the event record. */
  132. typedef void (*DialogHitFunc)(DialogPtr dialog, short itemhit, short modifiers);
  133.  
  134. /* EditDialogFunc is called by CallEditCommand when the frontmost window
  135.     is a dialog window.  For most purposes, you should call DialogEdit from
  136.     your edit function. */
  137. typedef void (*EditDialogFunc)(DialogPtr dialog, short editcmd);
  138.  
  139.  
  140. /* SetDialogFunctions sets the functions used for handling dialog events.   If you
  141.     set the edit parameter to NULL, then DialogEdit will be called for edit commands
  142.     destined for dialog windows.  Any one or all of the parameters may be NULL.  */
  143. void SetDialogFunctions(DialogEventFunc evtproc, DialogHitFunc hitproc, EditDialogFunc edit);
  144.  
  145. /* DialogAppendItems appends the DITL resource items to the bottom of the dialog
  146.     window resizing the window as appropriate.  *first_item is set to the index
  147.     of the first item added to the dialog.  If the new dialog routines are present
  148.     they are used, otherwise older glue code is used to append the items.  */
  149. OSErr DialogAppendItems(DialogPtr dialog, short id, short *first_item);
  150.  
  151.  
  152.  
  153. /* WINDOW COMMANDS */
  154.  
  155. /* CloseWindowFunc is called when TrackGoAway returns true for a window. */
  156. typedef void (*CloseWindowFunc)(WindowPtr window);
  157.  
  158. /* GrowWindowFunc is called when the FindWindow returns the inGrow result code.
  159.     where is the mouse position in global coordinates, and modifiers is copied from
  160.     the event record's modifiers field. */
  161. typedef void (*GrowWindowFunc)(WindowPtr window, Point where, short modifiers);
  162.  
  163. /* ZoomWindowFunc is called when FindWindow returns inZoomIn or inZoomOut.  partcode
  164.     is either inZoomIn or inZoomOut, and modifiers is copied from the event record's
  165.     modifiers field. */
  166. typedef void (*ZoomWindowFunc)(WindowPtr window, short partcode, short modifiers);
  167.  
  168. /* ClickWindowFunc is called whenever a mousedown occurs in a window's content
  169.     area.  where is the mouse location in local coordinates, count is the double-click
  170.     count measured using GetDblTime and modifiers is copied from the event record's
  171.     modifiers field */
  172. typedef void (*ClickWindowFunc)(WindowPtr window, Point where, short count, short modifiers);
  173.  
  174. /* ActivateWindowFunc is called whenever a window receives an activate event.  activate
  175.     is true if the window is becoming active. */
  176. typedef void (*ActivateWindowFunc)(WindowPtr window, Boolean activate);
  177.  
  178. /* UpdateWindowFunc is called for update events directed to a window.  you must call
  179.     BeginUpdate and EndUpdate yourself */
  180. typedef void (*UpdateWindowFunc)(WindowPtr window);
  181.  
  182. /* EditWindowFunc is called by CallEditCommand whenever a window is frontmost.
  183.     editcmd will be one of the edit menu items defined above.  */
  184. typedef void (*EditWindowFunc)(WindowPtr window, short editcmd);
  185.  
  186.  
  187. /* SetWindowManipulators sets the window callback routines used by the application for
  188.     manipulating the window.  Any or all of the parameters may be set to NULL depending
  189.     on what functionality is required. */
  190. void SetWindowManipulators(CloseWindowFunc close, GrowWindowFunc grow, ZoomWindowFunc zoom);
  191.  
  192. /* SetWindowInteraction sets the window callback routines used by the application for
  193.     interacting with the contents of the window.  Any or all of the parameters may be
  194.     set to NULL depending on what functionality is required. */
  195. void SetWindowInteraction(ClickWindowFunc click, EditWindowFunc edit);
  196.     
  197. /* SetWindowRedraw sets the window callback routines used by the application for
  198.     drawing the contents of the window.  Any or all of the parameters may be
  199.     set to NULL depending on what functionality is required. */
  200. void SetWindowRedraw(ActivateWindowFunc activate, UpdateWindowFunc update);
  201.  
  202.  
  203. /* SafeCloseWindow and SafeDisposeWindow are replacements for the standard
  204.     CloseWindow and DisposeWindow routines.  Before a window is removed from the
  205.     screen, if it is the active window, the ActivateWindowFunc is called with active
  206.     set to false. */
  207. void SafeCloseWindow(WindowPtr window);
  208. void SafeDisposeWindow(WindowPtr window);
  209.  
  210. /* ZoomWindowToSize zooms the window to a particular size.  On multiple monitor
  211.     systems the window is zoomed to the display intersecting with the largest area of
  212.     the window.  */
  213. void ZoomWindowToSize(WindowPtr window, short width, short height, short zoomDir);
  214.  
  215.  
  216.  
  217. /* KEYBOARD INPUT COMMAND */
  218.  
  219. /* KeyboardFunc is called for keyboard events.  key will be the ascii code
  220.     and ev is the event record. */
  221. typedef void (*KeyboardFunc)(char key, EventRecord *ev);
  222.  
  223.  
  224. /* SetKeyboardHook sets the keyboard hook for the application.  if no keyboard
  225.     hook is required, then you can set the parameter to NULL. */
  226. void SetKeyboardHook(KeyboardFunc keys);
  227.  
  228.  
  229.  
  230.  
  231. /* MISCELLANEOUS COMMANDS */
  232.  
  233. /* DiskInsertFunc will be called for disk inserted events. */
  234. typedef void (*DiskInsertFunc)(EventRecord *ev);
  235.  
  236. /* EventHookFunc is called at the beginning of CSAppEvent allowing your application
  237.     to filter events before they are processed through the callbacks.  if the function
  238.     returns true, then no further event processing happens, otherwise the event is
  239.     passed through the callbacks.  You can also use this routine to implement cursor
  240.     switching. */
  241. typedef Boolean (*EventHookFunc)(EventRecord *ev);
  242.  
  243. /* SwitcherFunc is called whenever an application switches from the foreground to the
  244.     background or vise versa.  If switching_in is true, then the application is
  245.     switching into the forground. */
  246. typedef void (*SwitcherFunc)(Boolean switching_in);
  247.  
  248.  
  249. /* SetMiscFunctions sets the callbacks for the above functions.  Any or all of the
  250.     parameters may be NULL depending one what routines are provided. */
  251. void SetMiscFunctions(DiskInsertFunc disk, EventHookFunc hook, SwitcherFunc switcher);
  252.  
  253.  
  254.  
  255.  
  256. /* MOVEABLE MODAL WINDOW COMMANDS */
  257.  
  258. /* MMHookFunc is called whenever the application's moveable modal dialog
  259.     state changes from on to off.  mmactive will be true if a moveable modal
  260.     dialog is now present on the screen.  This allows your application to disable
  261.     menus, et cetera.  */
  262. typedef void (*MMHookFunc)(Boolean mmactive); /* called with mm state changes */
  263.  
  264. /* SetMMHookProc sets the moveable modal mode switch hook that is called whenever
  265.     the application's moveable modal state switches from either on to off or off to on. */
  266. void SetMMHookProc(MMHookFunc mmhook);
  267.  
  268. /* GetMMWindow returns a pointer to the current moveable modal window, or NULL
  269.     if there is no current moveable modal window */
  270. WindowPtr GetMMWindow(void);
  271.  
  272. /* SetMMWindow returns a pointer to the last moveable modal window and sets the
  273.     new moveable modal window to target.  you can use combinations of GetMMWindow
  274.     and SetMMWindow together to save and restore the MM state and thereby nest
  275.     moveable modal windows. */
  276. WindowPtr SetMMWindow(WindowPtr target);
  277.  
  278. #endif
  279.